<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Make Controller Kit - Firmware API: Semaphores &amp; Mutexes</title>
<link href="mt_doxygen.css" rel="stylesheet" type="text/css" />
<link href="../resources/mt_doxytabs.css" rel="stylesheet" type="text/css" />
<style type="text/css">
<!--
.header {
	font-family: Verdana, Arial, Helvetica, sans-serif;
	font-size: 12pt;
	color: #222222;
}
-->
</style>
</head>

<body>
<table width="800" border="0">
    <tr>
      <td colspan="3">
        <form method="get" action="http://www.google.com/search">
          <div align="right">
            <input type="text"   name="q" size="25"
              maxlength="255" value="" />
            <input type="submit" value="Search" />
            <input type="hidden" name="sitesearch" value="makingthings.com/ref/firmware/html" />
          </div>
        </form>
       </td>
    </tr>
    <tr>
      <td><div align="center"><a href="http://www.makingthings.com">
				<img src="../resources/logo_brown_medium.png" alt="MakingThings"
									width="200" height="78" border="0" align="middle" longdesc="http://www.makingthings.com" /></a></div></td>
				<td><div align="center" class="header">
      		Make Controller Kit <br />
          Firmware API
      </div></td>
      <td><div align="center"><a href="http://www.makezine.com">
					<img src="../resources/make_logo.png" alt="MAKE Zine" 
										width="164" height="73" border="0" align="middle" longdesc="http://www.makezine.com" /></a></div></td>
    </tr>
</table>
</body>
</html>
<!-- Generated by Doxygen 1.5.4 -->
<script type="text/javascript">
<!--
function changeDisplayState (e){
  var num=this.id.replace(/[^[0-9]/g,'');
  var button=this.firstChild;
  var sectionDiv=document.getElementById('dynsection'+num);
  if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){
    sectionDiv.style.display='block';
    button.src='open.gif';
  }else{
    sectionDiv.style.display='none';
    button.src='closed.gif';
  }
}
function initDynSections(){
  var divs=document.getElementsByTagName('div');
  var sectionCounter=1;
  for(var i=0;i<divs.length-1;i++){
    if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){
      var header=divs[i];
      var section=divs[i+1];
      var button=header.firstChild;
      if (button!='IMG'){
        divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild);
        button=document.createElement('img');
        divs[i].insertBefore(button,divs[i].firstChild);
      }
      header.style.cursor='pointer';
      header.onclick=changeDisplayState;
      header.id='dynheader'+sectionCounter;
      button.src='closed.gif';
      section.id='dynsection'+sectionCounter;
      section.style.display='none';
      section.style.marginLeft='14px';
      sectionCounter++;
    }
  }
}
window.onload = initDynSections;
-->
</script>
<div class="tabs">
  <ul>
    <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
    <li><a href="modules.html"><span>Modules</span></a></li>
    <li><a href="classes.html"><span>Data&nbsp;Structures</span></a></li>
    <li><a href="files.html"><span>Files</span></a></li>
    <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  </ul>
</div>
<h1>Semaphores &amp; Mutexes<br>
<small>
[<a class="el" href="group___r_t_o_s.html">RTOS</a>]</small>
</h1>Thread-safe methods to protect access to shared resources.  
<a href="#_details">More...</a><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838">SemaphoreCreate</a> (void *semaphore)</td></tr>

<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Create a semaphore.  <a href="#gfa1700ecb9afca5ad4c1bcd832039838"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___semaphores_mutexes.html#g2637a3b208dd56f3313a7b3b3d9ea55d">SemaphoreTake</a> (void *semaphore, int blockTime)</td></tr>

<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Obtain a semaphore.  <a href="#g2637a3b208dd56f3313a7b3b3d9ea55d"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___semaphores_mutexes.html#gf6b6a05f387c0c8c671fe8c2491a5d43">SemaphoreGive</a> (void *semaphore)</td></tr>

<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Release a semaphore.  <a href="#gf6b6a05f387c0c8c671fe8c2491a5d43"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group___semaphores_mutexes.html#g4d883250a869e5064e92a3ae7ebc5c9e">SemaphoreGiveFromISR</a> (void *semaphore, int taskWoken)</td></tr>

<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Release a semaphore from within an ISR.  <a href="#g4d883250a869e5064e92a3ae7ebc5c9e"></a><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
Thread-safe methods to protect access to shared resources. 
<p>
Quite often you'll have more than one task trying to get access to the same resources. To ensure that the resource is not in some intermediate state between reading and writing, it's necessary to serialize access to it. Semaphores and mutexes provide a way to do this.<p>
Binary semaphores and mutexes are very similar but have some subtle differences: Mutexes include a priority inheritance mechanism, binary semaphores do not. This makes binary semaphores the better choice for implementing synchronisation (between tasks or between tasks and an interrupt), and mutexes the better choice for implementing simple mutual exclusion.<p>
A binary semaphore need not be given back once obtained, so task synchronisation can be implemented by one task/interrupt continuously 'giving' the semaphore while another continuously 'takes' the semaphore.<p>
The priority of a task that 'takes' a mutex can potentially be raised if another task of higher priority attempts to obtain the same mutex. The task that owns the mutex 'inherits' the priority of the task attempting to 'take' the same mutex. This means the mutex must always be 'given' back - otherwise the higher priority task will never be able to obtain the mutex, and the lower priority task will never 'disinherit' the priority.<p>
More info at <a href="http://www.freertos.org">http://www.freertos.org</a> - much documentation here used from the FreeRTOS doc by Richard Barry. <hr><h2>Function Documentation</h2>
<a class="anchor" name="gfa1700ecb9afca5ad4c1bcd832039838"></a><!-- doxytag: member="rtos.c::SemaphoreCreate" ref="gfa1700ecb9afca5ad4c1bcd832039838" args="(void *semaphore)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">void SemaphoreCreate           </td>
          <td>(</td>
          <td class="paramtype">void *&nbsp;</td>
          <td class="paramname"> <em>semaphore</em>          </td>
          <td>&nbsp;)&nbsp;</td>
          <td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Create a semaphore. 
<p>
Create a semaphore by using the existing queue mechanism. The queue length is 1 as this is a binary semaphore. The data size is 0 as we don't want to actually store any data - we just want to know if the queue is empty or full. <dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>semaphore</em>&nbsp;</td><td>The semaphore to be created.</td></tr>
  </table>
</dl>
<dl class="user" compact><dt><b>Example</b></dt><dd><div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span>* mySemaphore;
  <a class="code" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate</a>( mySemaphore );
  <span class="keywordflow">if</span>( mySemaphore != NULL )
  {
    <span class="comment">// The semaphore was created successfully and can now be used.</span>
  }
</pre></div> </dd></dl>

<p>Definition at line <a class="el" href="rtos_8c-source.html#l00894">894</a> of file <a class="el" href="rtos_8c-source.html">rtos.c</a>.</p>

</div>
</div><p>
<a class="anchor" name="gf6b6a05f387c0c8c671fe8c2491a5d43"></a><!-- doxytag: member="rtos.c::SemaphoreGive" ref="gf6b6a05f387c0c8c671fe8c2491a5d43" args="(void *semaphore)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int SemaphoreGive           </td>
          <td>(</td>
          <td class="paramtype">void *&nbsp;</td>
          <td class="paramname"> <em>semaphore</em>          </td>
          <td>&nbsp;)&nbsp;</td>
          <td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Release a semaphore. 
<p>
This must not be used from an ISR. See <a class="el" href="group___semaphores_mutexes.html#g4d883250a869e5064e92a3ae7ebc5c9e" title="Release a semaphore from within an ISR.">SemaphoreGiveFromISR( )</a> for an alternative which can be used from an ISR. <dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>semaphore</em>&nbsp;</td><td>The semaphore to release. </td></tr>
  </table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>1 if the semaphore was released. 0 if an error occurred. Semaphores are implemented using queues. An error can occur if there is no space on the queue to post a message - indicating that the semaphore was not first obtained correctly. </dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate( )</a>, <a class="el" href="group___semaphores_mutexes.html#g2637a3b208dd56f3313a7b3b3d9ea55d" title="Obtain a semaphore.">SemaphoreTake( )</a></dd></dl>
<dl class="user" compact><dt><b>Example</b></dt><dd><div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span>* mySemaphore;
  <a class="code" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate</a>( mySemaphore );
  <span class="keywordflow">if</span>( <a class="code" href="group___semaphores_mutexes.html#g2637a3b208dd56f3313a7b3b3d9ea55d" title="Obtain a semaphore.">SemaphoreTake</a>( mySemaphore, 1000 ) ) <span class="comment">// wait 1000 milliseconds on this semaphore</span>
  {
    <span class="comment">// access the protected resources</span>
    
    <span class="comment">// then release the semaphore</span>
    <span class="keywordflow">if</span>( !<a class="code" href="group___semaphores_mutexes.html#gf6b6a05f387c0c8c671fe8c2491a5d43" title="Release a semaphore.">SemaphoreGive</a>( mySemaphore ) )
      <span class="comment">// then handle the error here</span>
  }
</pre></div> </dd></dl>

<p>Definition at line <a class="el" href="rtos_8c-source.html#l00951">951</a> of file <a class="el" href="rtos_8c-source.html">rtos.c</a>.</p>

</div>
</div><p>
<a class="anchor" name="g4d883250a869e5064e92a3ae7ebc5c9e"></a><!-- doxytag: member="rtos.c::SemaphoreGiveFromISR" ref="g4d883250a869e5064e92a3ae7ebc5c9e" args="(void *semaphore, int taskWoken)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int SemaphoreGiveFromISR           </td>
          <td>(</td>
          <td class="paramtype">void *&nbsp;</td>
          <td class="paramname"> <em>semaphore</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&nbsp;</td>
          <td class="paramname"> <em>taskWoken</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Release a semaphore from within an ISR. 
<p>
This must not be used from an ISR. See <a class="el" href="group___semaphores_mutexes.html#g4d883250a869e5064e92a3ae7ebc5c9e" title="Release a semaphore from within an ISR.">SemaphoreGiveFromISR( )</a> for an alternative which can be used from an ISR. <dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>semaphore</em>&nbsp;</td><td>The semaphore to release. </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>taskWoken</em>&nbsp;</td><td>This is included so an ISR can make multiple calls to <a class="el" href="group___semaphores_mutexes.html#g4d883250a869e5064e92a3ae7ebc5c9e" title="Release a semaphore from within an ISR.">SemaphoreGiveFromISR()</a> from a single interrupt. The first call should always pass in 0. Subsequent calls should pass in the value returned from the previous call. </td></tr>
  </table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>1 if the semaphore was released. 0 if an error occurred. Semaphores are implemented using queues. An error can occur if there is no space on the queue to post a message - indicating that the semaphore was not first obtained correctly.</dd></dl>
<dl class="user" compact><dt><b>Example</b></dt><dd><div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span>* mySemaphore;
  <a class="code" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate</a>( mySemaphore );
  <span class="keywordtype">void</span> TimerISR( )
  {
    <span class="keyword">static</span> <span class="keywordtype">int</span> taskWoken = 0;
    taskWoken = <a class="code" href="group___semaphores_mutexes.html#g4d883250a869e5064e92a3ae7ebc5c9e" title="Release a semaphore from within an ISR.">SemaphoreGiveFromISR</a>( mySemaphore, taskWoken );
    <span class="comment">// If taskWoken was set to true you may want to yield (force a switch)</span>
    <span class="comment">// here.</span>
  }
</pre></div> </dd></dl>

<p>Definition at line <a class="el" href="rtos_8c-source.html#l00978">978</a> of file <a class="el" href="rtos_8c-source.html">rtos.c</a>.</p>

</div>
</div><p>
<a class="anchor" name="g2637a3b208dd56f3313a7b3b3d9ea55d"></a><!-- doxytag: member="rtos.c::SemaphoreTake" ref="g2637a3b208dd56f3313a7b3b3d9ea55d" args="(void *semaphore, int blockTime)" -->
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int SemaphoreTake           </td>
          <td>(</td>
          <td class="paramtype">void *&nbsp;</td>
          <td class="paramname"> <em>semaphore</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&nbsp;</td>
          <td class="paramname"> <em>blockTime</em></td><td>&nbsp;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td><td width="100%"></td>
        </tr>
      </table>
</div>
<div class="memdoc">

<p>
Obtain a semaphore. 
<p>
The semaphore must have first been created with <a class="el" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate( )</a>. <dl compact><dt><b>Parameters:</b></dt><dd>
  <table border="0" cellspacing="2" cellpadding="0">
    <tr><td valign="top"></td><td valign="top"><em>semaphore</em>&nbsp;</td><td>The semaphore to take. </td></tr>
    <tr><td valign="top"></td><td valign="top"><em>blockTime</em>&nbsp;</td><td>The time, in milliseconds, to wait for the semaphore to become available. </td></tr>
  </table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>1 if the semaphore was obtained. 0 if blockTime expired without the semaphore becoming available. </dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate( )</a>, <a class="el" href="group___semaphores_mutexes.html#gf6b6a05f387c0c8c671fe8c2491a5d43" title="Release a semaphore.">SemaphoreGive( )</a></dd></dl>
<dl class="user" compact><dt><b>Example</b></dt><dd><div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span>* mySemaphore;
  <a class="code" href="group___semaphores_mutexes.html#gfa1700ecb9afca5ad4c1bcd832039838" title="Create a semaphore.">SemaphoreCreate</a>( mySemaphore );
  <span class="keywordflow">if</span>( <a class="code" href="group___semaphores_mutexes.html#g2637a3b208dd56f3313a7b3b3d9ea55d" title="Obtain a semaphore.">SemaphoreTake</a>( mySemaphore, 100 ) ) <span class="comment">// wait 100 milliseconds on this semaphore</span>
  {
    <span class="comment">// now access the protected resources</span>
  }
</pre></div> </dd></dl>

<p>Definition at line <a class="el" href="rtos_8c-source.html#l00924">924</a> of file <a class="el" href="rtos_8c-source.html">rtos.c</a>.</p>

</div>
</div><p>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Make Controller Kit</title>
<style type="text/css">
<!--
.footer {
	font-family: Verdana, Arial, Helvetica, sans-serif;
	font-size: 9pt;
	color: #999999;
}
-->
</style>
</head>

<body>
<hr size="1">
<div>
  <p class="footer">The Make Controller Kit is an open source project maintained by <a href="http://www.makingthings.com">MakingThings</a>.<br />
    MakingThings code is released under the <a href="http://www.apache.org/licenses/LICENSE-2.0.html" target="_blank">Apache 2.0 license</a>.<br />
    Bug tracker, development wiki and status can be found at <a href="http://dev.makingthings.com">http://dev.makingthings.com</a>.<br />
		This document was last updated on 5 Dec 2007.
</p>
</div>
<!-- Google Analytics Code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-769030-1";
urchinTracker();
</script>
</body>
</html>
